Apple IIgs Technote #53 - Desk Accessories and Tools
Apple Developer Technical Support
Copyright (c) 1990 Apple Users' Group, Sydney
Republished from Applecations, a publication of the Apple Users' Group, Sydney, Australia.


Apple II
Technical Notes
______________________________________________________________________________
                                                  Developer Technical Support
Apple IIGS
#53:    Desk Accessories and Tools

Revised by:    Dave Lyons November 1989
Written by:    Matt Deatherage & Jim Mensch March 1989

This Technical Note describes new guidelines for developers to help
applications and desk accessories live together in the same system at the same
time.
Changes since March 1989:  Added additional discussion and minor
revisions; corrected tool set numbers for Event Manager and QuickDraw
Auxiliary.
______________________________________________________________________________


Desk accessories vary widely in complexity.  Classic Desk Accessories (CDAs)
range from simple status-reporting programs to complete system-level debugging
utilities, and similarly, New Desk Accessories (NDAs) range from static
windows with pictures to nearly full-fledged applications.

This Note presents some new guidelines aimed at helping developers of both
applications and desk accessories to get their products to work together now
and in the future.


Tool Sets

The greatest conflict between applications and desk accessories, especially
NDAs, is the use of system tool sets.  The Apple IIGS Toolbox Reference,
Volume 1, defines which tools are available for use by NDAs. The Desk Manager
requires starting the following tool sets before calling FixAppleMenu (which
installs the names of the NDAs in the Apple menu):

    Tool Locator (#1)
    Memory Manager (#2)
    Miscellaneous Tools (#3)
    QuickDraw II (#4)
    Event Manager (#6)
    Window Manager (#14)
    Menu Manager (#15)
    Control Manager (#16)
    LineEdit (#20)
    Dialog Manager (#21)
    Scrap Manager (#22)

Since the Desk Manager requires starting these tools before calling
FixAppleMenu, NDAs may assume that these tools are all present and running, so
they do not need to check for their presence.  In addition to these
requirements by the Desk Manager, Apple strongly recommends that all
applications start the following tools:

    QuickDraw Auxiliary (#18)
    Font Manager (#27)

These two additional tools are so widely used by desk accessories that they
should be present.  NDAs may not assume their presence, but it is reasonable
to write an NDA that checks for them, with the assumption that they will
usually turn out to be available.


The Golden NDA Guideline

Developers who wish to maintain maximum compatibility between their NDAs and
applications, both now and in the future, should consider every environment
change they make with the following Golden NDA Guideline firmly in mind:

    "I, an NDA, pledge not to alter the environment of the application
    under which I run, and I will behave in such a way that the
    application runs the same whether I am present or not."

Of course, this guideline does not include such necessary tasks as the normal
(and reasonable) allocation of memory.  An application must be prepared to
handle a memory allocation call by a desk accessory, operating system, or even
a tool at unexpected times.  The guideline does, however, mean that your desk
accessory cannot change the operating environment, including such things as
the presence of tools and operating system parameters.  The following sections
detail some of the most important ways to follow the Golden NDA Guideline.


Desk Accessory Guidelines

Extra Tools

o    If an NDA needs to use a tool which is not guaranteed to be available
     (e.g., Standard File), it should check to see if the tool is already
     running.  If it is not running, the NDA must use LoadOneTool to load it,
     then it must start the tool before using it.  When finished with the
     tool, the NDA must shut it down and unload it with UnloadOneTool.  (A
     tool is already running if its xxxStatus function returns TRUE and no
     error.)

o    If an NDA needs to start up a tool and keep it started while letting
     the application continue to run, things quickly get complicated.

     The Golden NDA Guideline shows why this is true.  If your NDA starts a
     tool which the application is going to use but has not yet started
     (i.e., the Font Manager), and your NDA does not shut it down before the
     application regains control, the application will (in this example) get
     error $1B01 (Font Manager Already Started) when it makes an FMStartUp
     call.  Many applications stop gracelessly on getting a tool startup
     error.

     In this case, the Golden NDA Guideline means that an application must
     not be forced to check the status of a tool which it has not started.
     Applications are not required to do so, and most of them do not.

     A previous version of this Note advised NDAs to start up and shut down
     tools when their windows were activated and deactivated.  This approach
     isn't strong enough to solve all the problems, since the application may
     decide to start up tools based on menu items (which can still be
     selected while an NDA window is in front).

     The only completely safe way to use a tool that isn't already running is
     to start it, use it, and shut it back down without ever returning
     control to the application while the tool set is started.

     Starting QuickDraw Auxiliary when the application has not started it can
     get you into a lot of trouble:  an application that correctly implements
     320/640 mode switching will call QDShutDown and QDStartUp.  QuickDraw
     Auxiliary depends heavily on QuickDraw, and restarting QuickDraw while
     QuickDraw Auxiliary is active will easily toast you.

o    If your NDA allocates bank-zero work area space for tool sets, be sure
     to dispose of it at DeskShutDown time (when your DAInit entry is called
     for shutdown).  If you don't, the system will die with error $0201 when
     trying to launch a ProDOS 8 application, since GS/OS needs all of banks
     0 and 1 to start ProDOS 8.

o    Sound tools provide the one exception to the rule of freely using a tool
     which is already started.  Refer to the section on System Parameters for
     more details on using sound tools.

o    NDAs must not shut down tools which they have not started.

o    CDAs are nearly always modal, but by using the HeartBeat interrupt queue
     or other mechanisms, they can get control when the user is no longer
     "in" the CDA.  The list of guaranteed tools for NDAs does not apply to
     CDAs, and CDAs must be prepared to deal with the ProDOS 8 environment as
     well as GS/OS.

System Parameters

o    A desk accessory (CDA or NDA) must not change a system resource or
     parameter which cannot be restored to its original condition.  A
     trivial, but illustrative, example of this is the number of times a
     pull-down menu item blinks when you select it.  This number (three by
     default) may be changed with the SetMItemBlink call, but there is no
     corresponding GetMItemBlink call, so you cannot retrieve the current
     value.  Therefore, a desk accessory must not change this parameter, and
     the same rule applies to any other system parameter for which you cannot
     determine a current value.

o    This idea extends to calling tool startup functions. Even though a
     tool's startup function may not return an error when the tool is already
     active, the startup function could reset certain parameters upon which
     the application depends.  An example of this is TLStartUp for the Tool
     Locator.  A seemingly innocuous call, TLStartUp actually disconnects any
     user tool sets present, which, in this case, would most likely have been
     installed by the current application.  CDAs and NDAs must never call
     TLStartUp or TLShutDown.

     A desk accessory should not call any tool's startup function if the tool
     is already active.  The one exception to this rule is the Memory
     Manager's MMStartUp call, which a desk accessory may make to obtain its
     User ID.  Think of MMStartUp as a "GetMyID" call.

o    A desk accessory cannot use any of the sound tools if they are already
     started.  This is contrary to the rule for other tool sets, but it is
     required because there is no memory management of the sound RAM (or "DOC
     RAM").  If the Sound Tools (#8) are started, the application has
     exclusive control of the 64K DOC RAM used to play sounds.  Anything your
     desk accessory might put there could overwrite information the
     application needs.

     Saving and restoring DOC RAM around desk accessory usage is not
     sufficient.  Many of the sound functions are interrupt driven, altering
     the contents of DOC RAM only during sound interrupts, so your desk
     accessory might attempt to replace parts of DOC RAM which are being
     played.  Since there is no memory management of DOC RAM, desk
     accessories must avoid the sound functions of the IIGS if the
     application is already using them.

o    A desk accessory must not install user tool sets, because there is no
     arbitration of user tool set numbers.  User tool sets are the sole
     property of the current application.


Application Guidelines

To coexist peacefully with desk accessories, particularly NDAs, applications
generally need to follow the guidelines listed in the Desk Manager chapter of
the Apple IIGS Toolbox Reference, Volume 1.  However, those applications which
wish to ensure maximum compatibility now and in the future will also want to
adhere to the following:

o    Don't just start the Scrap Manager--use it.  Many desk accessories
     support cutting and pasting to exchange text and pictures with your
     application, but they can do it only if you use the Scrap Manager.  If
     you have a need for your own private scrap internally, you should still
     also use the Scrap Manager to exchange text and pictures with other
     applications and DAs.

o    Start tools at the beginning of your application and leave them started.
     Every time you call SystemTask or TaskMaster, a desk accessory may get
     control of the system, and if your application has shut down a tool that
     a desk accessory found running and is using, the DA might not be able to
     complete an operation.

     For maximum compatibility, do not shut down any tools which were ever
     active when you called SystemTask or TaskMaster.  You can start more
     tools, but do not shut down those which are already active.  If you
     intend to start a tool and not keep it started, use it then shut it down
     immediately, being sure not to call SystemTask or TaskMaster during that
     time.

o    Applications should not call CloseAllNDAs while shutting down.  Since
     DeskShutDown closes all open NDAs anyway, it's not necessary.  By not
     calling CloseAllNDAs, you allow the system or NDAs to tell the
     difference between just cleaning up and really wanting to close all
     the NDAs.

o    Applications should never make a Close call with reference number zero
     at file level zero.  (If you need to use Close with reference number
     zero, use GetLevel and SetLevel to avoid closing files you did not
     open.)

o    An application with some memory to spare can save NDAs time by providing
     them the additional tools which they are most likely to use.  If a desk
     accessory needs the List Manager and your application starts it, the
     desk accessory will run faster since it can avoid loading and starting
     the tool every time it gets control.


     The most common tools which desk accessories require besides those
     available in the standard Desk Manager set are QuickDraw Auxiliary
     (#18), the Print Manager (#19), Standard File (#23), the Font Manager
     (#27), and the List Manager (#28).  QuickDraw Auxiliary and the Font
     Manager are especially important--not only do they work well together,
     but they are also widely used.  In addition, FMStartUp can take a long
     time, and waiting for it every time you activate an NDA window can be
     really frustrating.  Many desk accessories also use the Print Manager,
     the List Manager, and Standard File, and if they are always available,
     desk accessories will work more smoothly with your application.


Further Reference:
______________________________________________________________________________
    o    Apple IIGS Toolbox Reference, Volume 1
    o    Programmer's Introduction to the Apple IIGS


THIS CONTENT COPYRIGHT © 2007, APPLE MACINTOSH USERS' GROUP, SYDNEY
Permission has been obtained to make this material available on the Internet.

Permission is hereby granted for non-profit user groups to republish this content.
PLEASE CREDIT THE AUTHOR AND THE SOURCE: Applecations, publication of the Apple Users' Group, Sydney, Australia

THIS PAGE COPYRIGHT © 2007, ANDREW ROUGHAN